# Связующая документация

### Основной синтаксис

Определение ссылки выглядит следующим образом: `[[scala.collection.immutable.List]]`.

Другими словами, определение ссылки представляет собой последовательность идентификаторов, разделенных знаком `.`. 
Идентификаторы также могут быть разделены с помощью `#`.

По умолчанию идентификатор `id` ссылается на первую (в исходном порядке) сущность с именем `id`. 
Идентификатор может заканчиваться на `$`, что заставляет его ссылаться на значение (объект, значение, given); 
идентификатор также может заканчиваться на `!`, что заставляет его ссылаться на тип (класс, псевдоним типа, член типа).

Ссылки разрешаются относительно текущего местоположения в источнике. 
То есть при документировании класса ссылки относятся к сущности, включающей класс (пакет, класс, объект); 
то же самое относится к документированию определений.

Специальные символы в ссылках могут быть экранированы обратной косой чертой, 
что вместо этого делает их частью идентификаторов. 
Например, `[[scala.collection.immutable\.List]]` ссылается на класс `immutable.List`, 
указанный в `package scala.collection`.

### Новый синтаксис

Определение ссылок Scaladoc было расширено, чтобы сделать их более удобными для записи и чтения в исходном коде. 
Также целью было сблизить связь и синтаксис Scala. 
Новые функции:

а) `package` может использоваться в качестве префикса для ссылки на прилагаемый пакет. Пример:

```dotty
 package utils
 class C {
   def foo = "foo"
 }
 /** See also [[package.C]]. */
 class D {
   def bar = "bar"
 }
```

Ключевое слово `package` помогает сделать ссылки на прилагаемый пакет короче 
и немного более устойчивым к рефакторингу имен.

б) `this` может использоваться в качестве префикса для ссылки на прилагаемый классоподобный пример:

```dotty
class C {
  def foo = "foo"
  /** This is not [[this.foo]], this is bar. */
  def bar = "bar"
}
```

Использование здесь ключевого слова помогает сделать ссылки более привычными, 
а также помогает ссылкам пережить изменения имени класса.

в) Обратные кавычки могут использоваться для экранирования идентификаторов. Пример:

```dotty
def `([.abusive.])` = ???
/** TODO: Figure out what [[`([.abusive.])`]] is. */
def foo = `([.abusive.])`
```

Ранее (версии 2.x) для ссылки на такие идентификаторы в Scaladoc требовалось экранирование обратной косой чертой. 
Теперь (версии 3.x) Scaladoc позволяет использовать знакомую обратную кавычку Scala.


### Зачем сохранять синтаксис Wiki для ссылок?

Есть несколько причин, по которым синтаксис Wiki сохранен для ссылок на документацию 
вместо повторного использования синтаксиса Markdown. 
Это:

- Безымянные ссылки в Markdown уродливы: `[](definition)` против `[[definition]]`
Безусловно, большинство ссылок в документации безымянные. Должно быть очевидно, как их писать.
- Поиск локального члена конфликтует с фрагментами URL: `[](#field)` против `[[#field]]`
- Разрешение перегрузки противоречит синтаксису MD: `[](meth(Int))` против `[[meth(Int)]]`
- Теперь, когда есть парсер для синтаксиса ссылок, 
можно разрешить пробелы внутри (в Scaladoc нужно было экранировать их косой чертой), 
но это не распознается как ссылка в Markdown: `[](meth(Int, Float))` против `[[meth(Int, Float)]]`

Ни одна из них не делает полностью невозможным использование стандартного синтаксиса ссылок Markdown, 
но они делают его гораздо более неуклюжим и уродливым, чем нужно. 
Кроме того, синтаксис ссылок Markdown даже не сохраняет никаких символов.


---

**Ссылки:**

- [Scaladoc Guide](https://docs.scala-lang.org/scala3/guides/scaladoc/linking.html)
